Programming With QuickTime VR

Entering and Leaving Nodes

The QuickTime VR Manager provides a way for you to be notified whenever the user is about to enter a new node or leave the current node. You can then react to these notifications in whatever manner you choose. For example, when the user is about to enter a new node, you might determine the name of that new node and display the name or other information about the node. Similarly, when the user is about to leave the current node, you might initiate a custom node-to-node transition effect. Alternatively, you can cancel the move to the other node; this might be useful in a game when the user hasn't yet searched the current node completely or accomplished some other predefined task in that node.

To be informed that the user is about to enter a new node, you define and install a node-entering procedure. Listing 2-8 illustrates a simple node-entering procedure that determines the name of the new node and then utters that name.

Listing 8 Informing the user of a new node's name



 
pascal OSErr MyEnteringNodeProc (QTVRInstance theInstance, 

                                    UInt32 theNodeID, SInt32 refCon)

{

    Str255          theString;

    OSErr           theErr;

    

    theErr = MyGetNodeName(theInstance, theNodeID, &theString);

    if (!theErr)

        SpeakString(theString);



    return(theErr);

}

See Listing 4-1 in "QuickTime VR Atom Containers" for the definition of the function MyGetNodeName defined in Listing 2-8 .

You install a node-entering procedure by calling the QTVRSetEnteringNodeProc function, like this:



 
theErr = QTVRSetEnteringNodeProc(theInstance, 

                    NewQTVREnteringNodeProc(MyEnteringNodeProc), 0, 0);

To be informed that the user is about to leave the current node, you define and install a node-leaving procedure. Listing 2-9 illustrates a simple node-leaving procedure that prevents the user from leaving the current node unless all hot spots in the node have been triggered.

Listing 9 Leaving a node



 
pascal OSErr MyLeavingNodeProc (QTVRInstance theInstance, 

                                UInt32 fromNodeID, UInt32 toNodeID, 

                                Boolean *cancel, MyDataPtr theDataPtr)

{

    Boolean theUserCanLeave = false;    //By default, user can't leave.



    if (theDataPtr->allHotSpotsTouched)

        theUserCanLeave = true;

    

    *cancel = !theUserCanLeave;

    return(noErr);

}

Before returning, your node-leaving procedure should set the Boolean value pointed to by the cancel parameter to false to accept the move from fromNodeID to toNodeID . Set that value to true to cancel the move and remain at the node specified by the fromNodeID parameter. The procedure defined in Listing 2-9 simply reads some private data to determine whether to allow the user to leave the current node.

You install a node-leaving procedure by calling the QTVRSetLeavingNodeProc function, like this:



 
theErr = QTVRSetLeavingNodeProc(theInstance,

        NewQTVRLeavingNodeProc(MyLeavingNodeProc), (SInt32)&theData, 0);

In a multinode movie, your node-entering procedure is not called for the first node. This is because the user is considered to be in the first node as soon as the VR movie is opened, before you have a chance to install your node-entering procedure. If you need to have your node-entering procedure called for the first node, you can execute it explicitly, either before or after you've installed it as a node-entering procedure.